Skip to main content

OpenTrans

Github Link: https://github.com/RainStorm108/OpenTrans

OpenTrans is a private local-LLM batch translation utility using Ollama. It is designed to mirror a source directory into a target language while preserving the exact file hierarchy.

Key Features​

  • Local (Ollama): Private, cost-free translation using models like Gemma, Llama 3, or DeepSeek.
  • Syntax Shielding: Automatically protects code blocks (```), inline code (`), LaTeX math ($), and Markdown links from being corrupted by the LLM.
  • Directory Mirroring: Recursively replicates your source folder structure in the output destination.
  • Parallel Processing: Uses ThreadPoolExecutor for high-speed batch handling of large file sets.
  • Smart Caching: Uses hashing to track file changes. Only files that have been modified since the last run are sent to the LLM, saving significant time and compute resources.
  • Resilient File Handling: Automatically pulls required models from Ollama with a real-time progress bar if they are missing.

Quick Usage​

Simply provide the input directory and the target output directory.

opentrans ./docs ./translated_docs --config ./config.yaml

Example Output:

Target Language: Chinese
Input:  /home/user/Projects/OpenTrans/docs
Output: /home/user/Projects/OpenTrans/translated_docs
Using Model: translategemma:4b

Translating Files: 100%|████████████████████████████████| 12/12 [00:45<00:00, 3.7s/file]

Complete.

Running Examples​

# Translating Docusaurus
opentrans ./Example/Docusaurus/docs ./Example/Docusaurus/i18n/zh-hans/docusaurus-plugin-content-blog/current ./config.yaml

Installation​

Setup​

OpenTrans requires Ollama to be installed and running on your local machine.

  1. Install Ollama: Follow instructions at Ollama

  2. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install .
  1. Install OpenTrans
git clone https://github.com/rainstorm108/OpenTrans.git
cd OpenTrans
uv pip install .
  1. run
opentrans ./docs ./translated_docs --config ./config.yaml

For Developers​

  1. Environment Setup
uv sync
source .venv/bin/activte
hatch shell
uv pip install -e .
  1. Running Tests
hatch test

Folder Structure​

OpenTrans/
├── src/
│   └── OpenTrans/
│       ├── __init__.py        
│       ├── main.py            # CLI interface using Click
│       ├── settings.py        # Translate settings
│       ├── translator.py      # Translate logic
│       ├── cache_manager.py   # Manages translation caching using content hashing to skip unchanged files.
│       └── hasher.py          # Hash file for cache
├── tests/
│   ├── test_cache_manager.py
│   ├── test_hasher.py
│   └── test_translator.py
├── config.yaml                # Global settings (model, language, etc.)
├── pyproject.toml
└── README.md

Workflow​

Todo​

  • Click-based CLI interface
  • Placeholder-based syntax protection (Code/LaTeX)
  • Multi-threaded parallel processing
  • Implement hash caching to skip unchanged files
  • Finish the Docusaurus translate script
  • User Tree-sitter to replace the code blocks before translation instead of regex
  • Add support for more file types
  • ...

License​

This project is licensed under the MIT License.